---
id: BillingService
version: 0.0.1
name: Billing Service
summary: >-
  Manages billing cycles, invoice generation, and payment scheduling for
  subscriptions
tags:
  - billing
  - subscriptions
  - invoicing
repository:
  url: 'https://github.com/eventcatalog/billing-service'
receives:
  - id: PaymentProcessed
sends:
  - id: InvoiceGenerated
  - id: SubscriptionPaymentDue
owners:
  - dboyne
attachments:
  - url: 'https://example.com/adr/001'
    title: ADR-001 - Use Kafka for asynchronous messaging
    type: architecture-decisions
    icon: FileTextIcon
  - url: 'https://example.com/adr/001'
    title: ADR-002 - Database per service
    icon: FileTextIcon
    type: architecture-decisions
specifications:
  - type: graphql
    path: schema.graphql
    name: GraphQL API
readsFrom:
  - id: order-metadata-store
---

import Footer from '@catalog/components/footer.astro'

## Overview

The Billing Service is responsible for managing all billing-related operations for subscriptions. It calculates billing cycles, generates invoices, and coordinates with payment services to ensure timely payment collection.

## Key Features

- **Billing Cycle Management**: Handles daily, weekly, monthly, quarterly, and annual billing cycles
- **Invoice Generation**: Creates detailed invoices with line items and tax calculations
- **Payment Scheduling**: Schedules recurring payments based on billing cycles
- **Proration**: Calculates prorated charges for mid-cycle changes
- **Dunning Management**: Handles failed payment retry logic

## API Endpoints

### REST API
- `GET /api/billing/invoice/{subscriptionId}` - Get current invoice
- `GET /api/billing/history/{subscriptionId}` - Get billing history
- `POST /api/billing/preview` - Preview upcoming charges
- `PUT /api/billing/retry/{invoiceId}` - Retry failed payment

## Billing Cycle States

```mermaid
stateDiagram-v2
    [*] --> Scheduled
    Scheduled --> Processing
    Processing --> Paid
    Processing --> Failed
    Failed --> Retrying
    Retrying --> Paid
    Retrying --> Suspended
    Paid --> [*]
    Suspended --> [*]
```

## Configuration

```yaml
billing_service:
  cycles:
    - daily
    - weekly
    - monthly
    - quarterly
    - annual
  retry_attempts: 3
  retry_interval_days: [1, 3, 7]
  invoice_generation_lead_days: 7
```

<Footer />
